@bridge-ds/core 0.18.0 → 0.20.0

package/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright (c) 2026 Florian Gouloubi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
+to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of
+the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.

package/bridge.config.schema.json

@@ -13,6 +13,12 @@
       "const": 1,
       "description": "Config format version."
     },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 60,
+      "description": "The team's display name, shown in Studio, the Library and invitations (\"Acme Design\"). Absent: Bridge names the team after its repository."
+    },
     "repo": {
       "description": "GitHub repository. Pull requests target defaultBranch; Bridge never writes to it.",
       "oneOf": [
@@ -452,6 +458,11 @@
           "description": "For a design system run by one person. When true and the owners resolve to exactly one person who holds both roles, that person's approval counts as the design and the tech approval, so Tier 2 and Tier 3 changes can be approved. The author of a change still never approves it. Default false: one person never covers both approvals alone.",
           "default": false
         },
+        "leadsPublishTier1": {
+          "type": "boolean",
+          "description": "Leads can publish small changes without review. When true (or absent), team admins and the reviewers of the matching domain (design for docs and guidance, tech for code-only Tier 1) publish a Tier 1 change directly: Bridge opens the pull request, waits for the checks and merges it, recording who published it. A failing check sends it to review instead. Tier 2 and 3 are unchanged. Changing it is a Tier 3 change (bridge.config.json is a guardrail file).",
+          "default": true
+        },
         "rights": {
           "type": "object",
           "additionalProperties": false,
@@ -700,6 +711,16 @@
         }
       }
     },
+    "demo": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["viewer"],
+      "description": "A public demo's persona, read by Bridge's own demo repositories only: who a visitor without an account stands in for on the demo home (\"Good morning, Dana.\"). Ignored on any other repository.",
+      "properties": {
+        "viewer": { "type": "string", "minLength": 1, "description": "The persona's first name, for example \"Dana\"." },
+        "role": { "type": "string", "description": "What they do, for example \"DS lead\"." }
+      }
+    },
     "visualImpact": {
       "type": "object",
       "additionalProperties": false,

package/dist/audit/index.js

@@ -1,6 +1,6 @@
-import { i as isAuditable, a as auditFile } from "../report-DVEmUr0p.js";
-import { A, b, c, C, D, d, F, I, L, e, M, N, f, g, h, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z, B, E, G, H, J, K, O, P, Q, R, S, T, U, V, W, X, Y, Z } from "../report-DVEmUr0p.js";
-import { p as pieceId, a as proposedTokenPath, t as tokenLabel } from "../prod-branch-DenQkr_e.js";
+import { i as isAuditable, a as auditFile } from "../report-CE-jHAuw.js";
+import { A, b, c, C, D, d, F, I, L, e, M, N, f, g, h, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z, B, E, G, H, J, K, O, P, Q, R, S, T, U, V, W, X, Y, Z } from "../report-CE-jHAuw.js";
+import { p as pieceId, a as proposedTokenPath, t as tokenLabel } from "../prod-branch-CJZwMfVD.js";
 const lines = (text) => text.split(/\r?\n/);
 function lineBag(text) {
   const bag = /* @__PURE__ */ new Map();

package/dist/audit/report.d.ts

@@ -44,8 +44,23 @@ export interface CssFixEdit {
     to: string;
     token: string;
 }
-/** Safe autofix for a CSS/SCSS/Less file: exact token matches become var(--token). Returns the edits and the new text. */
-export declare function planCssFixes(text: string, lang: 'css' | 'scss' | 'less', ds: DesignSystemIndex): {
+/** A value the fix leaves as it is, like the audit leaves it out of the counts: an ignore comment or the allowlist. */
+export interface CssFixKept {
+    line: number;
+    column: number;
+    from: string;
+    reason: string;
+    via: 'comment' | 'allowlist';
+}
+/**
+ * Safe autofix for a CSS/SCSS/Less file: exact token matches become var(--token). Returns the edits and the new text.
+ * The same exceptions as the audit: a `bridge-audit-ignore-next-line: reason` comment on the line above, and the
+ * allowlist entries of this file, keep the value (listed in `kept`).
+ */
+export declare function planCssFixes(text: string, lang: 'css' | 'scss' | 'less', ds: DesignSystemIndex, opts?: {
+    allowlist?: AllowlistEntry[] | undefined;
+}): {
     edits: CssFixEdit[];
     output: string;
+    kept: CssFixKept[];
 };

package/dist/branch-actions.d.ts

@@ -1,10 +1,15 @@
 import type { GitHubClient, Review } from './github-client';
 import { type MergeMethod, type MissingApproval } from './review-gate';
-/** Merges a branch at the head the person saw (GitHub refuses when it moved meanwhile). Studio's Merge button: squash. */
+/**
+ * Merges a branch at the head the person saw (GitHub refuses when it moved meanwhile). Studio's Merge button: squash.
+ * `draft`: GitHub still calls it a draft though the gate reads it ready (core isDraft, `drafted-by-claude`), so it is
+ * marked ready for review first: GitHub never merges a draft.
+ */
 export declare function mergeOnGitHub(gh: GitHubClient, input: {
     number: number;
     headSha: string;
     method?: MergeMethod | undefined;
+    draft?: boolean | undefined;
 }): Promise<{
     sha: string;
 }>;
@@ -28,6 +33,7 @@ export declare function overrideMergeOnGitHub(gh: GitHubClient, input: {
     reason: string;
     missing: MissingApproval[];
     method: MergeMethod;
+    draft?: boolean | undefined;
 }): Promise<{
     sha: string;
     commentUrl: string;

package/dist/build-requests-github.d.ts

@@ -0,0 +1,25 @@
+import { type BuildRequestInput, type BuildRequestView, type LibraryArrival, type PublishOutcome } from './build-requests';
+import type { GitHubClient } from './github-client';
+/**
+ * Files a build request: one issue, labeled component-change (the bridge-jira Action mirrors it to Jira when set up),
+ * bridge-build, the request kind and the source. `labels` and `assignees` come from integrations.requests. Returns the
+ * outcome the plugin shows ("Build request sent").
+ */
+export declare function createBuildRequestOnGitHub(gh: GitHubClient, input: BuildRequestInput, opts?: {
+    labels?: string[] | undefined;
+    assignees?: string[] | undefined;
+    componentUrl?: string | undefined;
+}): Promise<PublishOutcome>;
+/**
+ * Every build request with its status, read from GitHub: the component-change and bridge-build issues, and the pull
+ * requests that close them or are library branches from Figma. Two to three list calls, no per-item reads.
+ */
+export declare function listBuildRequestsOnGitHub(gh: GitHubClient, opts?: {
+    now?: Date | number | undefined;
+    nameOf?: ((login: string) => string) | undefined;
+}): Promise<BuildRequestView[]>;
+/**
+ * Where a token push the plugin published as `shipped` stands: poll it until `final` ("In the library", or "Held for a
+ * developer" / "Not shipped"). Reads the pull request, its checks and its reviews.
+ */
+export declare function libraryArrivalOnGitHub(gh: GitHubClient, n: number): Promise<LibraryArrival>;

package/dist/build-requests.d.ts

@@ -0,0 +1,403 @@
+import { type BridgeConfig } from './config';
+import { type ComponentChangeRequest, type RequestIssue, type RequestKind } from './requests';
+import { type ChangedFile, type TokenChangeKind, type TokenChangeSummary } from './risk';
+import { type CiSummary } from './review-gate';
+/** Every build request issue carries this label (with component-change, which the Jira Action mirrors). */
+export declare const BUILD_REQUEST_LABEL = "bridge-build";
+/** The label the plugin puts on what it pushes (token pull requests, suggestions and requests). */
+export declare const SOURCE_FIGMA_LABEL = "source: figma";
+/** A build request waits this many days before it reads as stale. */
+export declare const BUILD_STALE_DAYS = 7;
+/**
+ * What the two images of a build request are called on designer screens (Studio): the component as it is in code
+ * now, and the design in Figma. The data keeps its field names, `before` and `after`; the GitHub issue table, read by
+ * developers, keeps Before and After.
+ */
+export declare const BUILD_IMAGE_LABEL: {
+    readonly before: "In code now";
+    readonly after: "In Figma";
+};
+/**
+ * Whether a pull request (or issue) was pushed from the Figma plugin: the `source: figma` or `from-figma` label, or the
+ * hidden "From Figma" origin block of a component branch.
+ */
+export declare function isFigmaPush(p: {
+    labels?: readonly ({
+        name?: string;
+    } | string)[] | null | undefined;
+    body?: string | null | undefined;
+}): boolean;
+/**
+ * What a push from Figma changes, from the pull request's real files and token changes (never from what its body says):
+ * - `token-values`: token files only (values changed or tokens added), plus changesets, docs and Bridge's own files;
+ * - `token-structure`: a token renamed or removed;
+ * - `token-unknown`: token files changed but the token changes were not read (counts like token-structure);
+ * - `component`: component or other source code (a Claude draft branch, the pull request of a build request);
+ * - `outside`: a guardrail file (CI, AGENTS.md, bridge.config.json, contrast checks): no Figma credit at all.
+ */
+export type FigmaPushScope = 'token-values' | 'token-structure' | 'token-unknown' | 'component' | 'outside';
+/** A token file: `*.tokens.json`, or a JSON file under `tokens.root`. */
+export declare function isTokenPath(path: string, config?: BridgeConfig | undefined): boolean;
+export declare function figmaPushScope(input: {
+    files: readonly ChangedFile[];
+    tokenChanges: readonly {
+        kind: TokenChangeKind | string;
+    }[] | null | undefined;
+    config?: BridgeConfig | undefined;
+}): FigmaPushScope;
+/**
+ * Whether the token files of a pull request are worth reading to tell a token value change (isTokenValueChange): it
+ * changes token files, and nothing beside them but changesets, docs and Bridge's own files. Every other pull request
+ * (code, a guardrail file, no token file) is not one, with no read.
+ */
+export declare function mayBeTokenValueChange(files: readonly ChangedFile[], config?: BridgeConfig | undefined): boolean;
+/**
+ * Decision TV-1 (docs/BUILD-REQUESTS.md, "Token values from Studio"): a pull request that only changes token values
+ * (values changed or tokens added, from its real files and token changes, never from its body), whoever opened it.
+ * Once the design approval is given it ships after the automatic checks, with no developer code OK (review-gate
+ * withTokenValueApprovals, branchVerdict `tokenValues`). A rename or removal, unread token changes (null), code, a
+ * guardrail file or a running exploration is not one: those still need the tech approval.
+ */
+export declare function isTokenValueChange(input: {
+    files: readonly ChangedFile[];
+    tokenChanges: readonly {
+        kind: TokenChangeKind | string;
+    }[] | null | undefined;
+    config?: BridgeConfig | undefined;
+    labels?: readonly ({
+        name?: string;
+    } | string)[] | null | undefined;
+}): boolean;
+/**
+ * The token changes between two versions of token files, by kind, from their text alone (DTCG: a node with `$value` is a
+ * token, its path the keys joined by "."). For callers that only have the files of a pull request (the server arming a
+ * merge, Studio's branch page): a path gone is `removed` (a rename reads as removed plus added, which gates the same),
+ * a new path `added`, a different `$value`, `$type` or extension `changed`, a different `$description` only
+ * `changed` with descriptionOnly. Unreadable JSON throws, so the caller treats the changes as unknown.
+ */
+export declare function tokenFileChanges(files: readonly {
+    before: string | null | undefined;
+    after: string | null | undefined;
+}[]): TokenChangeSummary[];
+/** The Figma push facts the gate reads (branchVerdict `figmaPush`). Null when the pull request is not one. */
+export interface FigmaPush {
+    scope: FigmaPushScope;
+}
+/**
+ * The Figma push facts of a pull request: pushed from the plugin (isFigmaPush), or the pull request of a build request
+ * sent from Figma (`closesFigmaBuildRequest`: its body closes one). Null otherwise, and for a running exploration.
+ */
+export declare function figmaPushOf(pr: {
+    labels?: readonly ({
+        name?: string;
+    } | string)[] | null | undefined;
+    body?: string | null | undefined;
+}, facts: {
+    files: readonly ChangedFile[];
+    tokenChanges: readonly {
+        kind: TokenChangeKind | string;
+    }[] | null | undefined;
+    config?: BridgeConfig | undefined;
+    closesFigmaBuildRequest?: boolean | undefined;
+}): FigmaPush | null;
+/** Whether a scope ships with no person in the loop: design approved by the push, tech approved by being values only. */
+export declare const shipsByItself: (scope: FigmaPushScope | null | undefined) => boolean;
+/**
+ * Where one published thing went:
+ * - `shipped`: a token pull request with values only. Bridge merges it once the automatic checks pass (auto-merge
+ *   armed); poll libraryArrival until it reads "In the library".
+ * - `waiting-for-developer`: a pull request a developer approves first (a token renamed or removed).
+ * - `build-request`: an issue developers build from (a structure change).
+ */
+export type PublishRoute = 'shipped' | 'waiting-for-developer' | 'build-request';
+export interface PublishOutcome {
+    /** What was published: a token path, or a component name. */
+    subject: {
+        type: 'token' | 'component';
+        name: string;
+    };
+    route: PublishRoute;
+    /** The pull request (shipped, waiting-for-developer) or the issue (build-request). */
+    ref: {
+        kind: 'pull' | 'issue';
+        number: number;
+        url: string;
+    };
+    /**
+     * `shipped` only: whether Bridge armed the merge (auto-merge on GitHub, or the Bridge app merging on green checks).
+     * False when it could not (no Bridge app on the repository, auto-merge off): the route is then reported as
+     * `waiting-for-developer` instead, so this is true on every `shipped` outcome.
+     */
+    armed?: boolean | undefined;
+}
+export interface PublishResult {
+    outcomes: PublishOutcome[];
+}
+export declare const PUBLISH_ROUTE_COPY: Record<PublishRoute, {
+    label: string;
+    sentence: string;
+}>;
+/**
+ * The route of a token push, from its token changes: values changed or tokens added ship; a rename or a removal waits
+ * for a developer. `armed` false (Bridge could not arm the merge) also waits for a developer.
+ */
+export declare function tokenPublishRoute(changes: readonly {
+    kind: TokenChangeKind | string;
+}[], armed?: boolean): Exclude<PublishRoute, 'build-request'>;
+/** One sentence for the end of a publish: "2 on their way to the library, 1 waiting for a developer, 1 build request sent." */
+export declare function publishSummary(r: PublishResult): string;
+export type LibraryArrivalKey = 'on-its-way' | 'in-the-library' | 'held' | 'not-shipped';
+export interface LibraryArrival {
+    key: LibraryArrivalKey;
+    label: string;
+    sentence: string;
+    /** Stop polling: it is in the library, or it will not get there by itself. */
+    final: boolean;
+}
+/**
+ * Where a published pull request stands, for the plugin to poll after `shipped` (every 20 to 30 seconds is plenty)
+ * and for Studio. Never names a technical blocker: a failing check, a conflict or a change request all read "Held for a
+ * developer". `held` is final for polling on a conflict or a change request (a person picks it up from there), not on a
+ * failed check, which a re-run can clear.
+ */
+export declare function libraryArrival(p: {
+    state: string;
+    merged_at?: string | null | undefined;
+    merged?: boolean | undefined;
+    mergeable?: boolean | null | undefined;
+    ci?: CiSummary | null | undefined;
+    changesRequested?: number | undefined;
+}): LibraryArrival;
+/** The review Bridge's app leaves on a token push it ships (the merge rule's record on GitHub). */
+export declare const FIGMA_SHIP_HEADING = "**Bridge: shipped from Figma**";
+export declare function figmaShipReviewBody(by?: string | null): string;
+/** A prop (option) the build needs. */
+export interface BuildProp {
+    name: string;
+    /** "variant", "boolean", "text", "instance swap", or a TypeScript type. */
+    type?: string | undefined;
+    values?: string[] | undefined;
+    default?: string | undefined;
+    /** "new", "changed" or "removed"; default new. */
+    change?: 'new' | 'changed' | 'removed' | undefined;
+    note?: string | undefined;
+}
+/** What a build request adds to a component change request (kept in the request's hidden block, under `build`). */
+export interface BuildRequestExtra {
+    v: 1;
+    /** Image URLs of the design before and after the change. */
+    before?: string[] | undefined;
+    after?: string[] | undefined;
+    props?: BuildProp[] | undefined;
+    /** Where the full spec lives, when it is not in the issue (too large): a path on a branch, or a URL. */
+    specPath?: string | undefined;
+}
+/** The input of the build request issue builder (the Figma plugin, Studio, the CLI and the MCP server). */
+export interface BuildRequestInput {
+    /** Coded name ("Button"), or the proposed name of a new component. */
+    component: string;
+    kind: RequestKind;
+    /** One line, sentence case: "Add a lg size". */
+    title: string;
+    /** What and why, in the designer's words. */
+    summary: string;
+    /** What changes for developers in one sentence. */
+    line?: string | undefined;
+    changes?: ComponentChangeRequest['changes'] | undefined;
+    figma: {
+        fileKey?: string | undefined;
+        nodeId?: string | undefined;
+        nodeName?: string | undefined;
+        url?: string | undefined;
+    };
+    images?: {
+        before?: string[] | undefined;
+        after?: string[] | undefined;
+    } | undefined;
+    props?: BuildProp[] | undefined;
+    /** The structured spec (the plugin's ComponentPushDiff, with its token edits), shown collapsed. Omitted when too large. */
+    spec?: unknown;
+    specPath?: string | undefined;
+    /** A brief for Claude written by the caller; default buildRequestBrief. */
+    brief?: string | undefined;
+    source: ComponentChangeRequest['source'];
+    /** GitHub login of who pushed, when known (the "Requested by" record). */
+    requestedBy?: string | undefined;
+}
+/** Kinds that are structure changes, so a push from Figma becomes a build request. */
+export declare const BUILD_KINDS: readonly RequestKind[];
+/** The largest spec JSON kept in the issue body (GitHub caps a body at 65,536 characters). */
+export declare const BUILD_SPEC_MAX = 30000;
+/** The request a build request input stands for (what parseRequestIssue reads back, with `build`). */
+export declare function buildRequestOf(input: BuildRequestInput): ComponentChangeRequest & {
+    build: BuildRequestExtra;
+};
+/**
+ * The brief Claude gets to build it ("Copy brief for Claude" in Studio, `bridge build show` in the CLI,
+ * `bridge_get_build_request` in the MCP server). Without an issue number (inside the issue body), it says "this issue".
+ */
+export declare function buildRequestBrief(r: ComponentChangeRequest & {
+    build?: BuildRequestExtra | undefined;
+}, ctx?: {
+    issue?: number | undefined;
+    issueUrl?: string | undefined;
+    componentsDir?: string | undefined;
+    agentsFile?: string | undefined;
+    files?: string[] | undefined;
+}): string;
+/**
+ * The GitHub issue of a build request: a component change request issue (component-change, so the bridge-jira Action
+ * mirrors it to Jira) with the bridge-build label, before and after images side by side, the props needed, the spec
+ * collapsed and the brief for Claude collapsed. parseBuildRequestIssue reads it back.
+ */
+export declare function composeBuildRequestIssue(input: BuildRequestInput, opts?: {
+    labels?: string[] | undefined;
+    assignees?: string[] | undefined;
+    componentUrl?: string | undefined;
+}): RequestIssue;
+/** The build request in an issue body, or undefined when it has no Bridge request block. `build` is empty for a plain request. */
+export declare function parseBuildRequestIssue(body: string | null | undefined): (ComponentChangeRequest & {
+    build: BuildRequestExtra;
+}) | undefined;
+/** The spec kept collapsed in a build request issue, or undefined. */
+export declare function parseBuildSpec(body: string | null | undefined): unknown;
+/** Whether an issue is a build request: every component change request is one (bridge-build marks the new ones). Explorations are not. */
+export declare function isBuildRequestIssue(labels: readonly ({
+    name?: string;
+} | string)[] | null | undefined): boolean;
+/**
+ * Requested (nobody assigned) -> Picked up (assigned: "Ana is on it") -> In progress (a linked draft pull request, or a
+ * linked branch with commits) -> In review (a linked pull request ready for review) -> Shipped (merged, or the issue
+ * closed as completed). `not-planned`: closed as not planned.
+ */
+export type BuildStatus = 'requested' | 'picked-up' | 'in-progress' | 'in-review' | 'shipped' | 'not-planned';
+export declare const BUILD_STATUS_LABEL: Record<BuildStatus, string>;
+/** Steps of the status timeline, in order (not-planned is off the line). */
+export declare const BUILD_STEPS: readonly BuildStatus[];
+/** A pull request linked to a build request (closes it, or the build request is that branch). */
+export interface BuildPullLike {
+    number: number;
+    url?: string | undefined;
+    /** "open", "closed" or "merged" (PullRequestSummary), or GitHub's open/closed with merged_at. */
+    state: string;
+    draft?: boolean | undefined;
+    mergedAt?: string | null | undefined;
+    merged_at?: string | null | undefined;
+    labels?: readonly ({
+        name?: string;
+    } | string)[] | undefined;
+    author?: string | undefined;
+    assignees?: string[] | undefined;
+    createdAt?: string | undefined;
+    updatedAt?: string | undefined;
+    body?: string | undefined;
+    /** Commits on the branch, when known (a branch with only the spec commit is not work in progress). */
+    commits?: number | null | undefined;
+    headRef?: string | undefined;
+    title?: string | undefined;
+}
+export interface BuildIssueLike {
+    number: number;
+    url: string;
+    title: string;
+    body: string;
+    state: 'open' | 'closed';
+    stateReason?: string | null | undefined;
+    labels: readonly ({
+        name?: string;
+    } | string)[];
+    author?: string | undefined;
+    assignees?: string[] | undefined;
+    createdAt: string;
+    closedAt?: string | null | undefined;
+}
+export interface BuildStatusEvent {
+    status: BuildStatus;
+    /** ISO date, when GitHub says. */
+    at?: string | undefined;
+    /** Who, when it is a person ("ana"). */
+    who?: string | undefined;
+}
+export interface BuildRequestView {
+    /** "issue-12" or "pull-34". */
+    id: string;
+    /** Where it lives: an issue, or (direct mode, no issue) the library branch from Figma waiting for a developer. */
+    kind: 'issue' | 'pull';
+    number: number;
+    url: string;
+    component: string;
+    /** "Add a lg size": the request's title, without the component prefix. */
+    title: string;
+    requestKind: RequestKind | null;
+    status: BuildStatus;
+    label: string;
+    /** One designer sentence: "Ana is on it.", "Waiting for a developer for 9 days." */
+    sentence: string;
+    /** Who works on it: the assignees, else the author of the linked pull request in progress. */
+    builders: string[];
+    requestedBy: string | null;
+    createdAt: string;
+    ageDays: number;
+    /** Requested for more than BUILD_STALE_DAYS days. */
+    stale: boolean;
+    shippedAt: string | null;
+    /** The linked pull request that moves it furthest. */
+    pull: {
+        number: number;
+        url?: string | undefined;
+        state: string;
+    } | null;
+    /** Jira key from the bridge-jira Action's `jira: DS-12` label. */
+    jira: string | null;
+    figmaUrl: string | null;
+    /** The status timeline: each step reached, with when and who when GitHub says. */
+    timeline: BuildStatusEvent[];
+}
+/** The issue numbers a pull request links: "Closes #n" in its body, plus GitHub's linked issues when the caller read them. */
+export declare function linkedIssueNumbers(p: Pick<BuildPullLike, 'body'>, extra?: readonly number[]): number[];
+/** The Jira key the bridge-jira Action labelled an issue with ("jira: DS-12"), or null. */
+export declare function jiraKeyOfLabels(labels: readonly ({
+    name?: string;
+} | string)[] | null | undefined): string | null;
+/**
+ * The status of one build request, from GitHub only: the issue (state, reason, assignees) and the pull requests linked
+ * to it. `nameOf` turns a login into the name a designer knows (team members), default the login.
+ */
+export declare function buildRequestStatus(x: {
+    issue?: BuildIssueLike | null | undefined;
+    pull?: BuildPullLike | null | undefined;
+    linked?: readonly BuildPullLike[] | undefined;
+}, now?: Date | number, nameOf?: (login: string) => string): Pick<BuildRequestView, 'status' | 'label' | 'sentence' | 'builders' | 'ageDays' | 'stale' | 'shippedAt' | 'pull' | 'timeline' | 'createdAt'>;
+/**
+ * Every build request, from the issues and pull requests read on GitHub: issues that are build requests
+ * (isBuildRequestIssue) with the pull requests that close them, plus library branches from Figma waiting for a
+ * developer that no issue covers (direct mode). `linkedByIssue`: GitHub's linked pull requests per issue number, when the
+ * caller read the timeline (Development links), on top of "Closes #n".
+ */
+export declare function assembleBuildRequests(input: {
+    issues: readonly BuildIssueLike[];
+    pulls: readonly BuildPullLike[];
+    now?: Date | number | undefined;
+    nameOf?: ((login: string) => string) | undefined;
+    linkedByIssue?: ReadonlyMap<number, readonly number[]> | undefined;
+}): BuildRequestView[];
+/** The filters of the Being built page. */
+export type BuildFilter = 'all' | 'waiting' | 'in-progress' | 'shipped-this-week';
+export declare const BUILD_FILTER_LABEL: Record<BuildFilter, string>;
+/** Whether a build request shows under a filter. "All" leaves out what was closed as not planned more than a week ago. */
+export declare function matchesBuildFilter(v: Pick<BuildRequestView, 'status' | 'shippedAt' | 'timeline'>, f: BuildFilter, now?: Date | number): boolean;
+/** Build requests still open (not shipped, not closed). */
+export declare const openBuildRequests: <V extends Pick<BuildRequestView, "status">>(views: readonly V[]) => V[];
+/** The calm summary line of the home: "3 being built, 1 waiting to be picked up." Null when nothing is open. */
+export declare function buildSummaryLine(views: readonly Pick<BuildRequestView, 'status' | 'stale'>[]): string | null;
+/**
+ * The Library component page line while build requests for a component are open: "Figma is ahead: 2 changes being
+ * built (Ana)." Null when none is open (it disappears once shipped).
+ */
+export declare function figmaAheadLine(views: readonly Pick<BuildRequestView, 'component' | 'status' | 'builders'>[], component: string, nameOf?: (login: string) => string): {
+    count: number;
+    builders: string[];
+    sentence: string;
+} | null;
+/** "Button: add a lg size", the issue title of a build request (same rule as every request). */
+export declare const buildRequestTitle: (r: Pick<BuildRequestInput, "component" | "title">) => string;

package/dist/changelog-model.d.ts

@@ -0,0 +1,102 @@
+export type ChangelogBump = 'major' | 'minor' | 'patch';
+export interface ChangelogEntry {
+    source: 'changeset' | 'release';
+    /** First sentence of the note, the row title. */
+    title: string;
+    /** Rest of the note's first paragraph, may be empty. */
+    detail: string;
+    kind: string;
+    bump: ChangelogBump | null;
+    packages: string[];
+    forYou: string;
+    /** The author wrote the "For you:" line (forYou is not the default for the bump). */
+    forYouAuthored?: boolean;
+    date?: string;
+    /** Changeset id: the commit sha prefix in a CHANGELOG.md, or the .changeset file path for pending ones. */
+    ref?: string;
+}
+export interface ChangelogReleasePackage {
+    name: string;
+    version: string;
+    /** Published to npm (not a private app). */
+    published: boolean;
+}
+export interface ChangelogRelease {
+    /** "v1.1.0" (the Library version, from @bridge-ds/react) or "core 0.3.1" when react is not in the release. */
+    name: string;
+    date?: string;
+    pending: boolean;
+    packages: ChangelogReleasePackage[];
+    entries: ChangelogEntry[];
+    announcement: string;
+}
+/** One "## x.y.z" section of a package CHANGELOG.md. */
+export interface ChangelogSection {
+    pkg: string;
+    version: string;
+    published: boolean;
+    notes: {
+        id: string;
+        bump: ChangelogBump;
+        text: string;
+    }[];
+}
+export declare const shortPackage: (name: string) => string;
+/** Splits a paragraph into sentences: ". ", "! " or "? " before a capital, a quote or a backtick, never inside `code`. */
+export declare function noteSentences(para: string): string[];
+/** Longest second sentence shown under a title; a longer one stays in the full notes rather than being cut. */
+export declare const CHANGELOG_DETAIL_MAX = 240;
+/**
+ * A note as a row: its first sentence is the title (no trailing period), the second one the description when it is
+ * short enough to read in a list, and the author's "For you:" line when there is one.
+ */
+export declare function splitNote(text: string): {
+    title: string;
+    detail: string;
+    forYou?: string;
+};
+/** Parses a package CHANGELOG.md into its version sections. "Updated dependencies" lines are not changes. */
+export declare function parseChangelogSections(md: string, pkg: string, published: boolean): ChangelogSection[];
+/** One pending .changeset/*.md file, or null when it is not a changeset. */
+export declare function parseChangeset(src: string, ref: string): ChangelogEntry | null;
+/**
+ * Groups version sections into releases. Sections released together share a date, or, when no date is known
+ * (shallow clone, no tags), share a changeset: the release action writes one changeset into every package it
+ * bumps. Each changeset shows once per release, with every package it touched. Newest first.
+ * `dateOf(pkg, version)` returns the release date (YYYY-MM-DD) or undefined; it never guesses.
+ */
+export declare function groupReleases(sections: ChangelogSection[], dateOf: (pkg: string, version: string) => string | undefined, libraryPackage?: string): Omit<ChangelogRelease, 'announcement'>[];
+/** Breaking first, then New, Fix, Internal; the notes' own order inside a kind. */
+export declare function sortChangelogEntries<T extends {
+    kind: string;
+}>(entries: T[]): T[];
+export declare function releaseAnnouncement(r: Omit<ChangelogRelease, 'announcement'>): string;
+/** Meta line of an entry: the bump in words, then the packages (short names). Over `max`, only a count. */
+export declare function releasePackagesLabel(packages: string[], max?: number): {
+    tags: string[];
+    count: string | null;
+};
+/** A release as the snapshot carries it: the announcement is left out (releaseAnnouncement(r) rebuilds it). */
+export type ChangelogReleaseRow = Omit<ChangelogRelease, 'announcement'>;
+export interface CollectReleasesInput {
+    /** Each package's CHANGELOG.md text, with its npm name and whether it is published (not private). */
+    changelogs: {
+        pkg: string;
+        published: boolean;
+        text: string;
+    }[];
+    /** Pending .changeset/*.md files: `ref` is the file path. README.md is not a changeset and is skipped by the caller. */
+    changesets?: {
+        ref: string;
+        text: string;
+    }[];
+    /** Release date (YYYY-MM-DD) of a package version, or undefined; never guessed. */
+    dateOf?: (pkg: string, version: string) => string | undefined;
+    /** Package whose version names a release ("v1.1.0"). */
+    libraryPackage?: string;
+}
+/**
+ * Every release of a repository, newest first: the pending changesets as "Coming in the next release" when there are
+ * any, then the published versions grouped by groupReleases. What the Changelog shows and the team snapshot carries.
+ */
+export declare function collectReleases(input: CollectReleasesInput): ChangelogReleaseRow[];